home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 5 / Apprentice-Release5.iso / Source Code / Libraries / Sherlock 2.0 / Mac v2.0 docs / Text Docs / Mac Introduction .txt < prev    next >
Text File  |  1996-04-05  |  6KB  |  136 lines
  1. Introducing Sherlock
  2.  
  3.  
  4.  
  5. Sherlock is a tracing and profiling tool for the C programming language.  Sherlock macros create 
  6. named instructions that you can enable or disable by name at any time.
  7.  
  8.  
  9. For instance, the TRACE macro takes two arguments.  The first argument is a tracepoint name 
  10. associated with the macro.  The  second argument is a list of one or more C statements, called the 
  11. tracepoint actions.  Here is an example of a call to the TRACE macro:
  12.  
  13.  
  14.     TRACE("abc", printf("i = %d\n", i));
  15.  
  16.  
  17. The tracepoint name is "abc".  The tracepoint action for this macro is the statement:
  18.  
  19.  
  20.     printf("i = %d\n", i);
  21.  
  22.  
  23. This tracepoint action is executed when control reaches the macro, but only if the tracepoint named 
  24. abc has been enabled.  To find out whether tracing for abc has been enabled, the TRACE macro 
  25. calls Sherlock’s support routines.  These routines maintain a database of information and statistics 
  26. about tracepoints.
  27.  
  28.  
  29. Typically, you enable Sherlock macros from the command line.  To enable the statement above, 
  30. add ++abc to the command line.  To disable the statement, add --abc to the command line.  You 
  31. can use the wildcard characters * and ? to disable groups of Sherlock macros.  For example, the 
  32. command line arguments ++* --abc* enables all tracing except for tracepoints whose names start 
  33. with abc.  The Macintosh version of Sherlock contains routines that create a file containing a 
  34. simulated command line.
  35.  
  36.  
  37. As stated above, tracepoint actions can contain any C statements (except initializers with braces).  
  38. Usually tracepoint actions will print the contents of variables or data structures.  The Macintosh 
  39. version of Sherlock creates a log window, to which  Sherlock sends its output by default.  Output 
  40. to the Sherlock window may also be copied to the log file.   A Sherlock argument of the form
  41.  
  42. ++>>file_name causes Sherlock to open the log file with the given name.  Any previous log file is 
  43. closed: only one log file can be opened at at time.
  44.  
  45.  
  46.  
  47. The exxx family of functions simulate stream output routines found in C++.  By default, these 
  48. functions send their output to the log window.  On the Macintosh, the tracepoint actions inside 
  49. Sherlock macros should use the exxx routines.  Using exxx routines the example above would be:
  50.  
  51.  
  52.     TRACE("abc", es("i = "); eint(i); enl());
  53.  
  54.  
  55. The es routine prints a string, the eint routine prints an integer, and the enl routine prints a newline.  
  56. Many other exxx routines exist: they provide a type-safe replacement for fprintf.  Most of these 
  57. functions are defined in the file LIBes.c, but the function es() itself must be defined in each 
  58. application.  See the file SDIF_es.c for a typical definition.
  59.  
  60.  
  61. Sherlock gathers statistics about tracing instructions.  Sherlock counts how many times each 
  62. macro was encountered and the time spent between special macros called entry macros and exit 
  63. macros.  You can to print these statistics at any time, either from Sherlock menu or by inserting the 
  64. SL_DUMP macro into your program.
  65.  
  66.  
  67. You can insert or delete Sherlock macros automatically, using the SPP and SDEL tools.  The SPP 
  68. application inserts Sherlock macros into your source code and the SDEL application deletes them.  
  69. However, Sherlock macros need never be removed from your program—undefining the 
  70. SHERLOCK compile-time variable causes all Sherlock macros to expand to do-nothing code.
  71.  
  72.  
  73. Macintosh support routines
  74.  
  75. The Macintosh version of Sherlock provides two additional support routines, w_mac_init and 
  76. w_applEvent, that simplify porting existing applications to the Macintosh.  These routines are 
  77. described fully in the Chapter called “Installing Sherlock.”
  78.  
  79.  
  80. w_mac_init optionally inserts various menus into the menu bar.  One of these menus is the 
  81. Sherlock menu. The Sherlock menu allows you to control tracing and statistics while your 
  82. application is running.  The w_mac_init function can also insert standard Apple, File and Edit 
  83. menus into your application.
  84.  
  85.  
  86. w_applEvent provides a minimal event loop.  w_applEvent need not be used in applications that 
  87. have their own event loop and handle their own menus.
  88.  
  89. The Sherlock Menu
  90.  
  91. The w_mac_init function inserts the Sherlock Menu into your application’s menu bar.  The 
  92. Sherlock Menu contains the following items:
  93.  
  94.  
  95. Menu item    Function
  96.  
  97. Options…    Enable or disable tracepoints using the Sherlock options dialog.
  98.  
  99.  
  100. Dump Stats    Prints statistics to the Sherlock window.
  101.  
  102.  
  103. Clear Stats    Clears all statistics.
  104.  
  105.  
  106. Open File…/Close File    Opens or closes the Sherlock log file.  When the Sherlock log is
  107.  
  108.     open,  all output to the Sherlock window is sent also to the log.
  109.  
  110.     
  111.  
  112. Close Window/Open Window    Opens or closes the Sherlock Window.
  113.  
  114.  
  115. User Dumps 1, 2 and 3    Calls the dumpCallBack routines.
  116.  
  117.  
  118.  
  119. The Sherlock Options Dialog
  120.  
  121. The Sherlock Options Dialog appears when you select the “Options” item from the Sherlock menu.  
  122. This dialog contains a text box labeled “Sherlock arguments.”  Enter the names of tracing 
  123. statements to be enabled or disabled in this box.  Precede the names of the tracing statements by 
  124. ++ or -- to enable or disable them respectively.  Use the wildcard characters * and ? to enable or 
  125. disable groups of tracing statements.  * stands for any string and ? stands for any character.
  126.  
  127.  
  128. For example, ++f enables the statement labeled f and --g disables the statement labeled g.  ++f* 
  129. enables all tracing statements whose name starts with f*.   Finally, ++f* --fa* enables all tracing 
  130. statements whose name starts with f except those tracing statements whose name starts with fa.  
  131. The order of these specifications is significant:  they are evaluated left to right.
  132.  
  133.  
  134. Check the box marked, Echo Sherlock output to a disk file…,  to send Sherlock output both to the 
  135. log window and to a disk file.
  136.